home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3dm / old-compression / clQueryFree.z / clQueryFree
Encoding:
Text File  |  1998-10-20  |  12.5 KB  |  265 lines
  1.  
  2.  
  3.  
  4. ccccllll RRRReeeeaaaadddd////WWWWrrrriiiitttteeee IIIImmmmpppplllliiiicccciiiitttt BBBBuuuuffffffffeeeerrrrssss((((3333ddddmmmm))))        ccccllll RRRReeeeaaaadddd////WWWWrrrriiiitttteeee IIIImmmmpppplllliiiicccciiiitttt BBBBuuuuffffffffeeeerrrrssss((((3333ddddmmmm))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      clQueryFree, clUpdateHead, clQueryValid, clUpdateTail, clDoneUpdatingHead
  10.      - Reading and writing data with implicit buffers
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ddddmmmmeeeeddddiiiiaaaa////ccccllll....hhhh>>>>
  14.  
  15.      iiiinnnntttt ccccllllQQQQuuuueeeerrrryyyyFFFFrrrreeeeeeee((((CCCCLLLLbbbbuuuuffffffffeeeerrrrHHHHddddllll bbbbuuuuffffffffeeeerrrrHHHHddddllll,,,, iiiinnnntttt ffffrrrreeeeeeeeAAAAmmmmoooouuuunnnntttt,,,,
  16.          vvvvooooiiiidddd ********ffffrrrreeeeeeeeDDDDaaaattttaaaa,,,, iiiinnnntttt ****ffffrrrreeeeeeeeWWWWrrrraaaapppp))))
  17.      iiiinnnntttt ccccllllUUUUppppddddaaaatttteeeeHHHHeeeeaaaadddd((((CCCCLLLLbbbbuuuuffffffffeeeerrrrHHHHddddllll bbbbuuuuffffffffeeeerrrrHHHHddddllll,,,, iiiinnnntttt aaaammmmoooouuuunnnnttttTTTTooooAAAAdddddddd))))
  18.      iiiinnnntttt ccccllllQQQQuuuueeeerrrryyyyVVVVaaaalllliiiidddd((((CCCCLLLLbbbbuuuuffffffffeeeerrrrHHHHddddllll bbbbuuuuffffffffeeeerrrrHHHHddddllll,,,, iiiinnnntttt vvvvaaaalllliiiiddddAAAAmmmmoooouuuunnnntttt,,,,
  19.          vvvvooooiiiidddd ********vvvvaaaalllliiiiddddDDDDaaaattttaaaa,,,, iiiinnnntttt ****vvvvaaaalllliiiiddddWWWWrrrraaaapppp))))
  20.      iiiinnnntttt ccccllllUUUUppppddddaaaatttteeeeTTTTaaaaiiiillll((((CCCCLLLLbbbbuuuuffffffffeeeerrrrHHHHddddllll bbbbuuuuffffffffeeeerrrrHHHHddddllll,,,, iiiinnnntttt aaaammmmoooouuuunnnnttttTTTTooooRRRReeeelllleeeeaaaasssseeee))))
  21.      iiiinnnntttt ccccllllDDDDoooonnnneeeeUUUUppppddddaaaattttiiiinnnnggggHHHHeeeeaaaadddd((((CCCCLLLLbbbbuuuuffffffffeeeerrrrHHHHddddllll bbbbuuuuffffffffeeeerrrrHHHHddddllll))))
  22.  
  23. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  24.      _b_u_f_f_e_r_H_d_l      A handle to a CL buffer.
  25.  
  26.      _f_r_e_e_A_m_o_u_n_t     The number of blocks of free space to wait for. If it is
  27.                     zero, then the current number of blocks of free space is
  28.                     returned without waiting.
  29.  
  30.      _f_r_e_e_D_a_t_a       A pointer to the returned pointer to the location of free
  31.                     space.
  32.  
  33.      _f_r_e_e_W_r_a_p       The number of blocks of free space that have wrapped to
  34.                     the beginning of the ring buffer.  If it is greater than
  35.                     zero, then the total free space is in two segments.
  36.  
  37.      _a_m_o_u_n_t_T_o_A_d_d    The number of blocks of free space that were written by
  38.                     the caller and are ready to be consumed by the library.
  39.  
  40.      _v_a_l_i_d_A_m_o_u_n_t    The number of blocks of valid data to wait for.  If it is
  41.                     zero, then the current number of blocks of valid data is
  42.                     returned without waiting.
  43.  
  44.      _v_a_l_i_d_D_a_t_a      A pointer to the returned pointer to the location of valid
  45.                     data.
  46.  
  47.      _v_a_l_i_d_W_r_a_p      The number of blocks of valid data that have wrapped to
  48.                     the beginning of the ring buffer.  If it is greater than
  49.                     zero, then the total valid data is in two segments.
  50.  
  51.      _a_m_o_u_n_t_T_o_R_e_l_e_a_s_e
  52.                     The number of blocks of valid data that were read by the
  53.                     caller and can be reused by the library.
  54.  
  55.  
  56. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  57.      These calls are part of the Compression Library's interface for managing
  58.      implicit buffers.  Implicit buffering is invoked by ccccllllCCCCoooommmmpppprrrreeeessssssss and
  59.      ccccllllDDDDeeeeccccoooommmmpppprrrreeeessssssss by giving NULL arguments for the input and output buffers.
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ccccllll RRRReeeeaaaadddd////WWWWrrrriiiitttteeee IIIImmmmpppplllliiiicccciiiitttt BBBBuuuuffffffffeeeerrrrssss((((3333ddddmmmm))))        ccccllll RRRReeeeaaaadddd////WWWWrrrriiiitttteeee IIIImmmmpppplllliiiicccciiiitttt BBBBuuuuffffffffeeeerrrrssss((((3333ddddmmmm))))
  71.  
  72.  
  73.  
  74.      For an overview of the Compression Library and its buffering strategy,
  75.      see CLintro(3dm).
  76.  
  77.      Implicit buffers in the CL are ring buffers with the newest data filled
  78.      in at the head and the oldest data removed at the tail.  The calls to
  79.      read and write data operate on block counts.  The size of a block is the
  80.      frame size in bytes for buffer type CL_BUF_FRAME, and is 1 byte for
  81.      buffer type CL_BUF_COMPRESSED.
  82.  
  83.      ccccllllQQQQuuuueeeerrrryyyyFFFFrrrreeeeeeee is used to find out how much free space is available and
  84.      where it is.
  85.  
  86.      ccccllllUUUUppppddddaaaatttteeeeHHHHeeeeaaaadddd is used to notify the library that data has been placed in
  87.      the ring buffer.
  88.  
  89.      ccccllllQQQQuuuueeeerrrryyyyVVVVaaaalllliiiidddd is used to find out how much valid data is available and
  90.      where it is.
  91.  
  92.      ccccllllUUUUppppddddaaaatttteeeeTTTTaaaaiiiillll is used to notify the library that valid data has been
  93.      consumed from the ring buffer and is no longer needed.
  94.  
  95.      ccccllllDDDDoooonnnneeeeUUUUppppddddaaaattttiiiinnnnggggHHHHeeeeaaaadddd is used to notify the library that no more data will
  96.      be written to the ring buffer, in which case readers of the buffer will
  97.      not block waiting for data to arrive.
  98.  
  99.  
  100. RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEESSSS
  101.      Each routine returns a negative error code on failure.
  102.  
  103.      On success, ccccllllQQQQuuuueeeerrrryyyyFFFFrrrreeeeeeee and ccccllllQQQQuuuueeeerrrryyyyVVVVaaaalllliiiidddd return the number of free or
  104.      valid blocks that are available before wrapping, ccccllllUUUUppppddddaaaatttteeeeHHHHeeeeaaaadddd and
  105.      ccccllllUUUUppppddddaaaatttteeeeTTTTaaaaiiiillll return the number of blocks updated, and ccccllllDDDDoooonnnneeeeUUUUppppddddaaaattttiiiinnnnggggHHHHeeeeaaaadddd
  106.      returns SUCCESS.
  107.  
  108.  
  109. NNNNOOOOTTTTEEEE
  110.      In the case of valid data which is wrapped and is in two segments, the
  111.      first segment can be accessed through _v_a_l_i_d_D_a_t_a and the pointer to the
  112.      second segment is the beginning of the ring buffer. This pointer to the
  113.      beginning of the ring buffer can be accessed by calling ccccllllQQQQuuuueeeerrrryyyyBBBBuuuuffffffffeeeerrrrHHHHddddllll.
  114.  
  115.  
  116. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS
  117.  
  118.    1111.... RRRReeeeccccoooorrrrdddd
  119.  
  120.      /* Create the frame (input) and compressed (output) buffers */
  121.      frameBufferHdl = clCreateBuf(compressorHdl, CL_BUF_FRAME,
  122.                                   numberOfFrames, bytesPerFrame, NULL);
  123.      compressedBufferHdl = clCreateBuf(compressorHdl, CL_BUF_COMPRESSED,
  124.                                        compressedBufferSize, 1, NULL);
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. ccccllll RRRReeeeaaaadddd////WWWWrrrriiiitttteeee IIIImmmmpppplllliiiicccciiiitttt BBBBuuuuffffffffeeeerrrrssss((((3333ddddmmmm))))        ccccllll RRRReeeeaaaadddd////WWWWrrrriiiitttteeee IIIImmmmpppplllliiiicccciiiitttt BBBBuuuuffffffffeeeerrrrssss((((3333ddddmmmm))))
  137.  
  138.  
  139.  
  140.      /* Write a frame from screen to buffer */
  141.      clQueryFree(frameBufferHdl, 1, &frameBuffer, &wrap);
  142.      lrectread(0, 0, width - 1, height - 1, frameBuffer);
  143.      clUpdateHead(frameBufferHdl, 1);
  144.  
  145.      /* Compress the frame */
  146.      clCompress(compressorHdl, 1, NULL, &compressedBufferSize, NULL);
  147.  
  148.      /* Copy compressed bytes to file */
  149.      while ((size=clQueryValid(compressedBufferHdl, 0, &buf, &wrap)) > 0) {
  150.        write(fd, buf, size);
  151.        clUpdateTail(compressedBufferHdl, size);
  152.      }
  153.  
  154.  
  155.    2222.... PPPPllllaaaayyyybbbbaaaacccckkkk
  156.  
  157.      /* Fill the compressed buffer */
  158.      while ((size=clQueryFree(compressedBufferHdl, 0, &buf, &wrap)) > 0) {
  159.        read(fd, buf, size);
  160.        clUpdateHead(compressedBufferHdl, size);
  161.      }
  162.  
  163.      /* Decompress a frame */
  164.      clDecompress(decompressorHdl, 1, 0, NULL, NULL);
  165.  
  166.      /* Read and display the frame */
  167.      clQueryValid(frameBufferHdl, 1, &frameBuffer, &wrap);
  168.      lrectwrite(0, 0, width-1, height-1, frameBuffer);
  169.      clUpdateTail(frameBufferHdl, 1);
  170.  
  171.  
  172.    3333.... MMMMuuuullllttttiiiipppprrrroooocccceeeessssssss RRRReeeeccccoooorrrrdddd
  173.  
  174.      ProduceFrameProcess() :
  175.      while (1) {
  176.        clQueryFree(frameBufferHdl, 1, &frameBuffer, &wrap);
  177.        lrectread(0, 0, width - 1, height - 1, frameBuffer);
  178.        clUpdateHead(frameBufferHdl, 1);
  179.      }
  180.  
  181.      CompressProcess() :
  182.      while (1)
  183.        clCompress(compressorHdl, 1, NULL, &compressedBufferSize, NULL);
  184.  
  185.      ConsumeCompressedDataProcess() :
  186.      while (1) {
  187.        size = clQueryValid(compressedBufferHdl, 0, &buf, &wrap);
  188.        write(fd, buf, size);
  189.        clUpdateTail(compressedBufferHdl, size);
  190.      }
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. ccccllll RRRReeeeaaaadddd////WWWWrrrriiiitttteeee IIIImmmmpppplllliiiicccciiiitttt BBBBuuuuffffffffeeeerrrrssss((((3333ddddmmmm))))        ccccllll RRRReeeeaaaadddd////WWWWrrrriiiitttteeee IIIImmmmpppplllliiiicccciiiitttt BBBBuuuuffffffffeeeerrrrssss((((3333ddddmmmm))))
  203.  
  204.  
  205.  
  206.    4444.... MMMMuuuullllttttiiiipppprrrroooocccceeeessssssss PPPPllllaaaayyyybbbbaaaacccckkkk
  207.  
  208.      ProduceCompressedDataProcess() :
  209.      while (1) {
  210.        size = clQueryFree(compressedBufferHdl, 0, &buf, &wrap);
  211.        read(fd, buf, size);
  212.        clUpdateHead(compressedBufferHdl, size);
  213.      }
  214.  
  215.      DecompressProcess() :
  216.      while (1)
  217.        clDecompress(decompressorHdl, 1, 0, NULL, NULL);
  218.  
  219.      ConsumeFrameProcess() :
  220.      while (1) {
  221.        clQueryValid(frameBufferHdl, 1, &frameBuffer, &wrap);
  222.        lrectwrite(0, 0, width - 1, height - 1, frameBuffer);
  223.        clUpdateTail(frameBufferHdl, 1);
  224.      }
  225.  
  226.  
  227. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  228.      CLintro(3dm), clCreateBuf(3dm), clDestroyBuf(3dm), clCompress(3dm),
  229.      clDecompress(3dm)
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.